uri: Unify example URL for RFC 3986 getters#5471
Conversation
This new example URL includes all possible components and each of the component includes a meaningful difference between the “normalized” and “raw” version to make it easy for a reader to see what each of the getters refers to and what kind of normalization to expect.
|
My original idea was to use a basic example just to illustrate the basic behavior of each method, and then to add another example to illustrate the specification specific behavior (wrt. normalization or IDNA). I'm not sure that people less familiar with URI topic will have an easy time to understand what's going on if they are presented such a long and complex URI. IMO the example would be more clear if the URI was shorter. An example: It's (more) difficult to find the fragment in the latter example, even for me, since there are a lot of unrelated symbols to skip. |
I think those folks in particular can benefit when all the examples use the same URL, since they can then compare the different getters to see which of the getters relates to which part of the URL. Having different URLs where some of the parts are left out can result in ambiguity. For example using Basically when I look at the documentation page for a specific getter, then I'm interested in the specifics of that getter. I think simpler URLs are better suited for the documentation of the constructor or |
This new example URL includes all possible components and each of the component includes a meaningful difference between the “normalized” and “raw” version to make it easy for a reader to see what each of the getters refers to and what kind of normalization to expect.